Tema 06 - Introducción a Quarto

Análisis de Datos Multivariantes aplicado al Marketing - Curso 2023/24
Universidad de Alicante

Pedro Albarrán

Dpto. de Fundamentos del Análisis Económico. Universidad de Alicante

El sistema de publicaciones Quarto

  • Orientado al análisis de datos reproducible: combina código, resultados y comentarios

  • Útil como cuaderno de trabajo del código y para comunicar resultados en un documento final para tomar decisiones

  • Instalar Quarto para vuestro sistema operativo desde aquí

  • La guía y referencia completa de Quarto están en su Web

  • Un documento de Quarto se renderiza, procesando cada componente (código, resultado de ejecutarlo y texto) para producir documentos en varios formatos: html, PDF, Word, presentaciones, etc.

Documentos de Quarto: Crear y Guardar

  • Un documento de Quarto se crea a partir de una plantilla en RStudio con o File > New File > Quarto Document

    • Podemos elegir Título, Autor/a y formato de salida (HTML, por defecto)
  • Se guarda con o con File > Save, con extensión .qmd

  • Se renderiza con Render al formato de salida elegido

  • En el botón de engranaje Engranaje se pueden cambiar algunas opciones

    • p.e., dónde se visualiza la salida (en ventana aparte o en RStudio)

Documentos de Quarto: formato de salida

  • El renderizado crea un archivo en el mismo directorio donde está el archivo de Quarto .qmd

  • En el caso de HTML, se crea tanto un archivo con extensión .html como un subdirectorio del mismo nombre con componentes necesarios (ej., imágenes, css)

    • solo podemos visualizar correctamente el archivo .html en cualquier navegador si copiamos a otro lugar tanto el .html como el subdirectorio
  • Para crear PDFs, se necesita una distribución de LaTeX: instala una escribiendo en la pestaña de “Terminal” (a la derecha de la consola):

quarto install tool tinytex

Documentos de Quarto: Texto con Markdown

  • Los componentes de texto están escritos en Markdown: un conjunto ligero de convenciones para archivos de texto sin formato. Por ejemplo,

    • todo lo escrito entre dos * como **Hola** se renderiza en negritas

    • se utiliza # para indicar encabezados de secciones

  • En el menú de ayuda tenemos una descripción completa (Markdown quick reference) y “chuletas” (Cheatsheets)

  • También son útiles la web de Quarto y este libro online.

  • RStudio incorpora un editor visual de documentos de Quarto, similar a un procesador de texto

Editor Visual de Quarto en RStudio

  • En documentos .qmd, se puede elegir entre editar la fuente (source) de Markdown, como texto sencillo, o editar el documento de forma Visual en

  • En el modo visual, en esa misma barra de herramientas se tienen accesos a

    • formatos de texto (negritas, cursivas, encabezamientos) y listas
    • insertar enlaces, imágenes, notas a pie de página, tablas
    • incluir ecuaciones (en LaTeX)
    • también insertar directamente código HTML, comentarios, etc.
  • Se puede configurar la corrección ortográfica en Tools > Global Options > Spelling: agregar/seleccionar el diccionario de Español

Formato en la cabecera: el bloque YAML

  • Al principio del documento, entre dos líneas con ---, se pueden especificar varias opciones del documento: título, autor, fecha, formato de salida
  • Los formatos de salida son html, pdf, docx (y otros en Quarto Presentations)

  • También se especifican opciones globales del documento, algunas específicas de cada tipo de salida (ver la referencia para html y otros formatos)

      ---
      title: "Título"
      author: Autor 
      date: 15-octubre-2023
      format:
        html:
          toc: true              # índice
          number-sections: true  # secciones numeradas
          embed-resources: true  # archivo html autocontenido
          theme: united          # más temas: https://bootswatch.com/3/
      ---

Fragmentos o celdas de código

  • Insertamos código en medio del texto con el icono (visual)

  • Si pulsamos , escribimos r y luego un código, el documento de salida incluirá el resultado de ejecutar el código

  • Podemos incluir un fragmento de código (de varias líneas), con , en el desplegable o Ctrl + Alt + I

  • Se puede personalizar cómo se muestran varios aspectos del código y de sus resultados

    • bien para una celda concreta de código, incluyendo opciones de celda

    • o para todo el documento en la cabecera: las opciones de html están en la sección de código de su referencia (y similar para otros formatos)

Opciones para una celda de código

  • Las opciones se incluyen al principio de una celda precedidas por #|

  • Se muestra el código en la salida con la opción echo: true (o no con echo: false)

  • Con la opción eval: false, el código se ejecuta: los resultados de ejecutarlo están disponibles y pueden mostrarse (o no con eval: false)

    • Si un fragmento no se evalua, sus resultados no están para otras celdas posteriores (p.e., cargamos datos o una biblioteca para usar luego)

  • Incluimos los resultados del código con output: true

  • También se pueden mostrar (o no) los mensajes, errores y avisos de ejecutar un código con las opciones message, error y warning, respectivamente.

  • La lista completa de opciones aquí

Opciones para una celda de código (cont.)

  • Cómo mostrar resultado

    • results: hide (no mostrar)
    • results: hold (mostrar todo, no el resultado de cada línea)

  • include: false no incluye ni el código ni su resultado, pero se evalúa

  • label: etiqueta para identificar la celda

  • code-fold: true oculta el código pero da opción a mostrarlo

  • fig-cap y tbl-cap para los títulos

  • Cómo mostrar los gráficos: fig-show

    • las opciones hide y hold son como en results
    • animate concatena varios gráficos en una animación

Opciones para una celda de código (y 3)

  • fig-width y fig-height: dimensiones (reales, en pulgadas) de una figura

  • out-width y out-height: ídem en el documento de salida (% de las reales)

  • fig-align: mostrar la figura centrada o alineada a derecha o izquierda

  • layout-ncol: en cuantas columnas se componen los resultados

ggplot(data = cars) + geom_histogram(aes(x = speed))  # en la izquierda
ggplot(data = cars) + geom_histogram(aes(x = dist))   # en la derecha

Opciones globales para todas las celdas

  • Si no se da un valor a las opciones en una celda, se usa el valor por defecto de Quarto o el definido globalmente en la cabecera.

  • En la cabecera, se pueden especificar las opciones de ejecución de código echo, eval, include, output, error, etc. en execute (ver aquí y aquí)

      ---
      execute:
        echo: false
        warning: false
      ---
  • También se pueden fijar en la cabecera muchas otras opciones, incluidas algunas que ya hemos visto (un listado completo aquí para html)

Opciones por defecto para todas las celdas (cont.)

    ---
    format:
      html:
        code-fold: true
        cap-location: bottom
        fig-align: center
        df-print: paged
    ---
  • La opción df-print especifica el método para visualizar tablas
  • También se pueden especificar algunas de estas opciones a través del renderizador de R knitr (descripción completa aquí).

Ejecución de código en un documento .qmd

  • Al renderizar un documento .qmd, se crea un nuevo espacio de trabajo y se ejecuta el código allí.

    • ese espacio de trabajo es distinto del que vemos en RStudio: diferentes objetos, incluyendo bibliotecas

    • el directorio de trabajo también es diferente: es el directorio donde se encuentra el .qmd

  • Es importante conocer si el código del documento .qmd ofrece los resultados deseado antes de renderizar.

  • Cuando tenemos varias celdas de código, algunas pueden depender de cálculos y objetos previos (datos, bibliotecas, resultados)

  • Se puede probar ejecutando el código del documento .qmd (sin renderizar): línea a línea, la celda completa con o todas las anteriores con

Ejecución de código en un .qmd (cont.)

  • Cuando ejecutamos el código sin renderizar, éste pasa pasa a la consola y forma parte del espacio de trabajo de la sesión actual de R.

  • Debemos asegurarnos de que la sesión actual incluye sólo resultados del código de celdas del documento para que nuestra prueba sea equivalente a lo que obtendríamos renderizando

  • Resulta útil incluir una celda código al principio del documento (que se evalúe pero no muestre código ni resultados) que incluya

    • rm(list = ls()): al ejecutar todas las celdas previas, empezamos con una sesión sin objetos y podemos probar el código de la celda actual

    • Todas las bibliotecas (ej., tidyverse) que utilizaremos en varias celdas

    • Fijar el directorio de trabajo para acceder a archivos (p.e., imágenes, datos). Esto es innecesario si hemos sido cuidadosos y creado el archivo .qmd como parte de un proyecto.

Mejorar la salida de tablas

  • Los resultados de muchas funciones de R no son visualmente “profesionales” en el documento de salida de .qmd

  • Varias bibliotecas cambian algunas salidas por defecto (printr) u ofrecen funciones para mejorarlas (pander::pandoc.table(), xtable::xtable())

  • Por ahora, veremos la función kable() de la biblioteca knitr

  • Más adelante veremos la biblioteca kableExtra, con más opciones.

    • kableExtra muestra “data frame”/“tibbles” como tablas

    • broom::tidy() (de tidyverse) convierte mucho objetos de R (como listas con resultados de comandos) en tibbles

  • Otras bibliotecas similares: modelsummary, stargazer

Comentarios finales: Dashboards (Tableros)

  • Los dashboards son un tipo de interfaz gráfica para los usuarios finales que ofrecen visualizaciones rápidas de indicadores o resultados clave

  • Estas presentaciones visuales e interactivas de los resultados de un análisis de datos puede ayudar a una comunicación más efectiva

  • Con Quarto se pueden crear varios tipos de dashboards interactivos, aunque no vamos a profundizar en ellos

  • En particular, Quarto trabaja con el paquete de R llamado Shiny que permite crear fácilmente aplicaciones web interactivas

  • Podéis encontrar ejemplos de las capacidades de Shiny en esta galería de aplicaciones

Comentarios finales: libros de notas Jupyter

  • Son otra forma de combinar texto, código y resultados en un documento

  • Desarrollados para Python, admiten varios lenguajes de programación

    • Quarto puede incluir celdas de código en otros lenguajes, incluido Python
  • Se crean, visualizan y ejecutan solo en navegadores web, aunque son fácilmente modificables, en su entorno de trabajo

  • Quarto renderiza libros de Jupyter, creados en .qmd o en su propio formato

  • Muchas herramientas están preparadas para Python y R porque se usan a menudo indistintamente o combinados